---
menu: Graduated Proposals
name: Exclusive Accordion (Explainer)
path: /components/accordion.explainer
pathToResearch: /components/accordion.research
layout: ../../layouts/ComponentLayout.astro
---

- [@dbaron](https://github.com/dbaron)
- Last updated: November 16, 2023
- Github discussions:
  - [openui/open-ui#725](https://github.com/openui/open-ui/issues/725) (Proposal for Exclusive Accordions)
  - [openui/open-ui#778](https://github.com/openui/open-ui/issues/778) (how valuable is having working exclusivity in subtrees not connected to a document)
  - [openui/open-ui#786](https://github.com/openui/open-ui/issues/786) (exclusively non-exclusive...)
  - [openui/open-ui#812](https://github.com/openui/open-ui/issues/812) (developer poll on behavior of exclusive accordion)
  - [openui/open-ui#925](https://github.com/openui/open-ui/issues/925) (UA ability for user to over-ride exclusive accordions functionality)
  - [w3c/html-aam#509](https://github.com/w3c/html-aam/issues/509) (describe grouping (and naming of the group) for exclusive accordions `<details name>`)
  - PR [whatwg/html#9400](https://github.com/whatwg/html/pull/9400) (Add name attribute for grouping details elements into an exclusive accordion)
- [Specification](https://html.spec.whatwg.org/multipage/interactive-elements.html#attr-details-name)
- [MDN blog on Exclusive Accordions](https://developer.mozilla.org/en-US/blog/html-details-exclusive-accordions/)
- [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details#multiple_named_disclosure_boxes)

{/* START doctoc generated TOC please keep comment here to allow auto update */}
{/* DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE */}

## Table of Contents

- [Background](#background)
- [Developer Demand for Exclusive Accordion](#developer-demand-for-exclusive-accordion)
- [User Needs](#user-needs)
- [Proposal](#proposal)
  - [Open design questions](#open-design-questions)
    - [Name](#name)
    - [Interaction with `open` attribute](#interaction-with-open-attribute)
    - [Printing](#printing)
    - [Existing issues with `details`](#existing-issues-with-details)
    - [Accordions with exactly one item open](#accordions-with-exactly-one-item-open)
  - [Possibly-resolved design questions](#possibly-resolved-design-questions)
    - [Changes to ARIA roles or keyboard behavior](#changes-to-aria-roles-or-keyboard-behavior)
    - [Use case for non-exclusive accordion semantic?](#use-case-for-non-exclusive-accordion-semantic)
    - [Scope](#scope)
- [Alternatives considered](#alternatives-considered)
  - [CSS Toggles](#css-toggles)
  - [Toggle (expand/collapse) button or attribute](#toggle-expandcollapse-button-or-attribute)
  - [Panelset](#panelset)

# Background

A **disclosure** widget
([research](/components/disclosure.research))
is a UI that shows a summary or heading along
with an indicator (sometimes a triangle or a plus sign) that allows the
widget to be expanded to show additional details.
An **accordion**
([research](/components/accordion.research))
is a sequence of related disclosure widgets.
Some accordions are **exclusive accordions**,
which means that at most one of the disclosures in that accordion
can be open at the same time.

The existing HTML
[`details` element](https://html.spec.whatwg.org/multipage/C#the-details-element)
represents a disclosure widget.
A sequence of `details` elements can be used for a non-exclusive accordion.
However, there is not a current web platform feature
for exclusive accordions.

It is worth noting that the HTML `details` element
is not currently as styleable as it needs to be to meet many use cases.
Improving styleability of `details` will be addressed in a
[separate proposal](https://github.com/dbaron/details-styling),
intended to address both better ability to style/replace the disclosure triangle,
and to fit the parts of a `details`
into different types of layout (such as grid).
For example, there is no standardized or interoperable way to
replace the disclosure triangle's image or to change its placement
relative to the summary or the rest of the content of the details.

# Developer Demand for Exclusive Accordion

Design systems that offer accordion widgets vary
as to whether those widgets are exclusive or not.
Based on the systems documented in the
[accordion research](/components/accordion.research),
it seems more common for them not to be exclusive,
however, some systems offer an option for being exclusive,
and some systems offer only exclusive accordions.

Some examples of exclusive accordions on live sites:
* [Parsons Table product page](https://www.roomandboard.com/catalog/dining-and-kitchen/tables/parsons-tables) at Room and Board (Style/Size/Top/Base accordion on right side of page)
* [Aaron Dining Chair product page](https://www.potterybarn.com/products/aaron-chair/) at Pottery Barn (Overview / Responsibly Made / Dimensions & Care / Shipping & Returns accordion on right side of page)
* [Saatva Classic Mattress product page](https://www.saatva.com/mattresses/saatva-classic) (a few pages down, with the first heading "Plush & breathable sleep surface")
* The "Property Details" section of a [Marriott Hotels hotel page](https://www.marriott.com/en-us/hotels/ispjj-fairfield-inn-new-york-jfk-airport/overview/)
* ...

Some examples of exclusive accordions where exactly one item is always
open (discussed below as an exact-exclusive accordion, which requires
some additional code in addition to the proposed markup):
* [Pixel 7 product page](https://store.google.com/product/pixel_7?hl=en-US) on the Google Store (one accordion in each of the sections on Performance, Photography and Video, Protection, and Pixel Portfolio)
* [Zachary's Chicago Pizza FAQ](https://zacharys.com/frequently-asked-questions/)
* ...

# User Needs

Developers regularly use exclusive accordions on the Web.
Today, that generally means that they build their own widget
rather than using a widget provided by the platform,
because there is no such widget.

This proposal is suggesting that we add features for exclusive accordions
to the platform.
Doing so would help users because
it would make (or at least would enable making)
the user experience
more consistent, and generally better, in a number of areas:
* keyboard shortcuts and focus handling,
* exposure via ARIA to assistive technology, and
* integration with browser features such as find-in-page.

Reducing the need for developers to build their own widgets
should also reduce the size of pages that use such widgets,
which reduces the time and bandwidth needed
for users to load those pages.

# Proposal

I propose to add an attribute to
[the `details` element](https://html.spec.whatwg.org/multipage/C#the-details-element).
All `details` elements in the same tree
that have the same value for this attribute
would form an exclusive accordion.
The syntax of this attribute and the rules for matching its values would match
[the `name` attribute](https://html.spec.whatwg.org/multipage/C#naming-form-controls:-the-name-attribute)
and its use in defining
[radio button groups](https://html.spec.whatwg.org/multipage/C#radio-button-group).

When these attributes are used to form a group, it means that
any user action or API that causes one of the `details` elements
in the group to open causes all other elements in the group to close.

## Open design questions

### Name

There are many options for naming this attribute,
and they differ as to how well they:
* are concise,
* indicate that something happens when multiple elements use the same value, and
* indicate that the attribute causes the grouped elements
  to become exclusive (so that only one can be open).

Choices for its name also differ as to whether they're already used
for other things in HTML.
(This could be either an advantage or a disadvantage.)
In particular, `name` is used for grouping related form controls.

Some possibilities for the attribute's name are
`name`, `group`, or `exclusive`.

**Proposed solution**: Use `name`,
since it's consistent with existing features.

### Interaction with `open` attribute

Should this grouping cause the insertion of a `details` element with
the `open` attribute already set to have the `open` attribute removed
if it would violate the grouping constraint?
If so, is such attribute removal on insertion acceptable
(both for its complexity and for conformance with architectural principles)?
If not, is it ok that we allow developers a loophole to
violate the exclusivity semantics?

(This applies both to insertion by the parser
and insertion through other methods like setting `innerHTML`.)

**Proposed solution**: Enforce exclusivity only for
user interactions,
use of the [`open` IDL attribute](https://html.spec.whatwg.org/multipage/C#dom-details-open),
or setting the `open` attribute via `setAttribute`
(or `setAttributeNS`, `setAttributeNode`, or `setAttributeNodeNS`).
Do not enforce exclusivity when the `open` attribute is set by the parser,
when it is set as a result of cloning a node,
or when an element is moved to a new document.
Do not enforce exclusivity for elements whose
[root](https://dom.spec.whatwg.org/#concept-tree-root)
is not a
[Document](https://dom.spec.whatwg.org/#interface-document)
or a
[ShadowRoot](https://dom.spec.whatwg.org/#interface-shadowroot).

### Printing

For many accordions, it is desirable for the print layout of the page
to have all items opened.
This is currently not possible to do from a style sheet,
but it probably should be possible,
and it's possible that it should be the default.
The presence of exclusive accordion semantics make this more difficult,
because of the rule that only one item can be open.
(However, some of the time it will make more sense to print what is
on the screen rather than printing all of the content.
It's also not clear to me how often distinguishing between these cases
should be a developer decision or should be based on a user decision.)

In theory this could be addressed with a model
where details elements were implemented on top of developer-exposed CSS Toggles,
and developers could disable the effects of those CSS Toggles when printing.
Or, more generally, this could be addressed with a solution
that treats things like accordions and tabs
as possible interactive presentations
of markup that is semantically headings and sections,
and allows the use of CSS (or some other mechanism tied to media queries)
to choose between them.
However, this would be a relatively major change, worthy of its own explainer.
It also has many of the same problems as CSS Toggles (see below).

It's also possible that developers could do this in JavaScript,
specifically for printing,
but then it certainly wouldn't be a default and probably wouldn't be done often.

We should find and consider alternative approaches for addressing this issue.

**Proposed solution**: For now, do nothing here.
If developers want all of the `details` elements on a page to print open,
they need to change both `name` and `open` attributes
during the
[`beforeprint`](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeprint_event)
and
[`afterprint`](https://developer.mozilla.org/en-US/docs/Web/API/Window/afterprint_event)
events.

### Existing issues with `details`

There are some existing issues with `details` elements
that may need to be resolved
before `details` elements can be used in a way
that fulfills the goals of this proposal.

First, there are issues related to interactive content
in the `summary` element
causing various keyboard and accessibility issues.
See https://github.com/whatwg/html/issues/2272
(and its links, which include browser bugs)
for details.
There are also some related questions about selection in `summary`
as discussed in
https://github.com/whatwg/html/issues/3191 and
https://github.com/whatwg/html/issues/8707 .

Second, there are some questions about the relationship between
headings and `summary` elements.
See https://github.com/whatwg/html/issues/8864 .
(This is not surprising since the accordion pattern
is one possible interactive presentation
of markup that is semantically pairs of headings and sections.)

Further reading:
* [Details / Summary Are Not [insert control here]](https://adrianroselli.com/2019/04/details-summary-are-not-insert-control-here.html)
* [Why `<details>` is Not an Accordion](https://daverupert.com/2019/12/why-details-is-not-an-accordion/)

### Accordions with exactly one item open

Some accordions (such as the one on the Pixel product page above)
always have exactly one item open,
and do not allow zero items to be open.
(This could be called an exact-exclusive accordion.)
This is a somewhat more complicated widget,
because the open/close control
disappears from the item that is open
or becomes disabled.
It's not clear how such widgets could be modeled with this design,
other than by ensuring that developer Javascript to handle this.

**Proposed solution**: For now, do not attempt to address this pattern directly,
but make sure it's possible to do in Javascript.

## Possibly-resolved design questions

### Changes to ARIA roles or keyboard behavior

It's possible that the presence of a group should
change the ARIA roles for the `details` or its `summary`
or change their default keyboard behavior.

If this is the case,
it seems likely that such changes
may also be desirable for non-exclusive accordions (see next question).

Based on the [discussion on 2023 April 27](https://github.com/openui/open-ui/issues/725#issuecomment-1525924478),
it seems like at least default keyboard behavior for accordions
is undesirable because it leads to bad user experience
particularly for users on small or highly-zoomed displays
(where the content of a single item is less likely to fit within the display).

### Use case for non-exclusive accordion semantic?

This design assumes that there isn't a use case for
the semantic of a non-exclusive accordion,
since a non-exclusive accordion is largely indistinguishable
from a sequence of disclosures (`details` elements).

However, it's possible there may be value in
establishing such a semantic connection
between the `details` elements
in a non-exclusive accordion.
(See previous question for one possible reason.)

If such connection is valuable,
then that would favor a design that separates the ideas
of connecting the `details` elements into a group
and making the group exclusive.

In the [discussion on 2023 April 27](https://github.com/openui/open-ui/issues/725#issuecomment-1525924478),
no use cases for a platform feature for connecting a non-exclusive accordion
were raised
(assuming the conclusion to the keyboard behavior issue above stays as-is).

### Scope

Should the name be scoped
to something smaller than the document (for example, only to siblings)
or to something larger than the document (such as the flat tree)?

I think scoping only to siblings would be problematic
because there are valid use cases
for putting each `details` element into some sort of sectioning markup,
and that scoping on the flat tree would be problematic because
having names cross shadow root boundaries would break encapsulation.

# Alternatives considered

## CSS Toggles

The [CSS Toggles](https://tabatkins.github.io/css-toggle/) proposal
is a much more complex proposal that would be able to describe
exclusive accordions and many other things.
However, it has a
[number of issues](https://docs.google.com/document/d/10JxXgeDAJ5zerOdxoWM9ZU9d5iMOdzGJt0EhlhkOkxM/edit)
related to developer experience,
accessibility, and other things, and it's not clear whether the proposal
is viable.

## Toggle (expand/collapse) button or attribute

The [proposal for a toggle (expand/collapse)](https://github.com/openui/open-ui/issues/700) feature
probably falls somewhere between this proposal and CSS Toggles
in terms of how general it is.
It may be a reasonable alternative to this proposal,
or it may be reasonable to do both.

I think it's possible that there's a risk that this proposal becomes
a more general feature than currently intended,
which would have both some of the advantages and some of the problems
that CSS Toggles have.

It's likely worth exploring this alternative further,
particularly to understand
what integration with CSS and JavaScript it would have,
and how that integration would affect its use.

## Panelset (aka "Spicy-Sections")

Within Open-UI there was another proposal 
which was to be called [panelset](https://tabvengers.github.io/spicy-sections/).
Earlier it was called "spicy sections" in order to avoid bikeshedding 
or misconceptions that it was yet ready to be thought of as a proposal.
The distinguishing characteristic of that proposal is that introduced
the idea that certain 'widgets' had more in common with scrollbars 
than they do inputs.  That is, they are often reasonable choices of 
design particular to the media or situation.  Panelsets proposed the 
introduction of other affordances to handle (in document, see also [559]( https://github.com/openui/open-ui/issues/559)) tabs and 
accordions. Thus, it is less general than CSS Toggles, but more 
general than all the others mentioned here.)

The panelset proposal has enough open questions that
it's a bit hard to assess.

At the same time,
this proposal and panelset address problem spaces that,
while intersecting,
are different enough
that it would still be reasonable
to do both if we conclude that both are good.
